Using messages

The message system provides a way to notify about events and to exchange information.

Messages and arguments

MessageArguments is the base class for arguments passed in messages. Kanzi provides built-in message types for different nodes and triggers. For example, the ButtonConcept::ClickedMessageArguments message for the Button: Click trigger and the Page::ActivatedMessageArguments message for the Page Activated trigger.

You can extend the MessageArguments class by writing your own message types.

Message type describes:

You can describe and access the message arguments with the PropertyType objects. MessageArguments::setArgument function sets and MessageArguments::getArgument function retrieves arguments with the underlying storage type for arguments, such as float, Boolean, and Vector3.

Dispatching messages

To dispatch messages to the handlers, use Node::dispatchMessage. This function defines the message type and arguments, and calls all the handlers which are registered for the node for that message type.

Node::dispatchMessage notifies the handlers immediately before the function call returns, which enables the handlers to react to the message immediately.

Receiving messages

All messages in Kanzi are routed messages. When a message is dispatched the system walks through the scene graph from the root node to the target of the message in a process called tunnelling and then walks back in a process called bubbling. At each passed node in the scene graph the system looks for handlers for the dispatched message. This allows you to install handlers at any place in the scene graph to intercept messages before they reach their destination, or to gather messages from several sources.

Handle messages during bubbling phase, and intercept or filter messages during the tunnelling phase.

Receivers are implemented as functions and passed as pointers to Node::addMessageHandler() and kzuMessageDispatcherAddTunnellingHandler(). To provide context to the receiver implementation, provide a pointer to the user data at registration time. Use Node::removeMessageHandler() to remove handlers.

Timers

The message system has inbuilt support for timers, accessible using KzuMessageDispatcher. kzuMessageDispatcherAddTimerHandler() subscribes and kzuMessageDispatcherRemoveTimerHandler() unsubscribes a timer. During subscription set the interval for the timer and the timer behavior:

Creating custom messages in Kanzi Studio

To create a custom message in Kanzi Studio:

  1. In the Library press Alt and right-click Property Types and select Property Type.

    The Property Type Editor opens.
  2. In the Property Type Editor set:
  3. Click Save.
    You can now use this custom message in your application.

See Setting the handling of trigger messages.

See also

Using input manipulators

Triggers

Using triggers